=============
Configuration
=============

SYNTAX
======

:file:`sieverc` consists of statements and comments, each of which
must occur on a line of its own. Comments start with a "#", which
may be preceded by whitespace. Empty lines are ignored, but may
not contain other whitespace.


STATEMENTS
==========

.. confvar:: account [login@]host

    Subsequent statements only apply to accounts matching `login` and `host`.
    If `login` is omitted, all accounts on `host` match.

.. confvar:: authmechs mechanism, ...

    Comma-separated list of authentication mechanisms, ordered by preference.

    Either a combination of password-based mechanisms:

    * ``scram-sha3-512-plus``
    * ``scram-sha-512-plus``
    * ``scram-sha-384-plus``
    * ``scram-sha-256-plus``
    * ``scram-sha-224-plus``
    * ``scram-sha-1-plus``
    * ``scram-sha3-512``
    * ``scram-sha-512``
    * ``scram-sha-384``
    * ``scram-sha-256``
    * ``scram-sha-224``
    * ``scram-sha-1``
    * ``plain``
    * ``cram-md5`` (obsolete)
    * ``login`` (obsolete)

    Or:

    * ``external``

    Shell-like patterns are expanded to non-obsolete
    mechanisms in the above order.

    Default: ``scram-*, plain``

.. confvar:: alias string

    Use `string` as alias for the current host.

.. confvar:: backup policy

    Emacs-like backup policy.
    One of:

    ``none``
        Do not make backups (default).

    ``simple``
        Back up :file:`file` to :file:`file~`.

    ``numbered``
        Back up :file:`file` to :file:`file.~{n}~`, where
        *n* starts with 1 and increments with each backup.

    See the GNU Emacs manual (chap. `19.3.2 <emacs-backup_>`_) for details.

.. confvar:: cafile file

    Load custom certificate authorities (CAs) from `file`.
    `file` must be in PEM format.

.. confvar:: cadir dir

    Load custom certificate authorities (CAs) from `dir`. `dir` must
    contain one PEM file per CA, each of which must be named after the
    hash of its subject name.

    .. only:: man

        See :man:`c_rehash(1)` for details.

    .. only:: html

        See SSL_CTX_load_verify_locations_ for details.

.. confvar:: cert file

    Read the client TLS certificate from `file`. `file` must be in PEM
    format and contain the private key, the client certificate, and every
    CA certificate required to establish the certificate's authenticity,
    in that order. Some ManageSieve servers also require that each CA
    certificate is followed by its certificate revocation list.

.. confvar:: confdir dir

    Configuration directory. Defaults to the directory that
    :file:`sieverc` was found in or, if :file:`sieverc` does
    not exist, :file:`{$XDG_CONFIG_HOME}/sieve`.

.. confvar:: confirm command, ...

    Comma-separated list of commands that require confirmation
    if they overwrite or remove a file.

    Either a combination of:

    * :subcommand:`cp`
    * :subcommand:`get` (also applies to :subcommand:`mget`)
    * :subcommand:`mv`
    * :subcommand:`put` (also applies to :subcommand:`mput`)
    * :subcommand:`rm`

    Or one of:

    * ``all`` (default)
    * ``none``

.. confvar:: getkeypass command

    Read the TLS key passphrase from the standard output of :samp:`{command}`.

.. confvar:: getpass command

    Read the login password from the standard output of :samp:`{command}`.

.. confvar:: host hostname|address

    Host to connect to (default: :file:`localhost`).

.. confvar:: key file

    Read the client TLS key from `file`, rather than from the certificate file.
    `file` must be in PEM format.

.. confvar:: login username

    Login as *username*.

.. confvar:: ocsp boolean

    Check whether the server's TLS certificate has been revoked?

    ``yes`` (default) or ``no``.

    .. danger::
        Only disable if the issuer of the server's
        TLS certificate does not support OCSP.

.. confvar:: port port

    Connect to `port` (default: 4190).

.. confvar:: timeout float

    Connection timeout in seconds. May be a fraction.

.. confvar:: tls boolean

    Secure connections with Transport Layer Security (TLS)?

    ``yes`` (default) or ``no``.

    .. danger::
        Data sent over an unsecured connection can be
        intercepted, read, and modified by third parties.

.. confvar:: saslprep credentials

    Which `credentials` to normalise.

    One of:

    * ``usernames``
    * ``passwords``
    * ``all`` (default)
    * ``none``

    Adjust if valid credentials are rejected.

.. confvar:: stacktrace boolean

    Show stack traces even for expected errors?

    ``yes`` or ``no`` (default).

.. confvar:: verbosity level

    One of:

    * ``error``
    * ``warning``
    * ``info`` (default)
    * ``debug``
    * ``auth`` (show authentication exchange)

    The higher the level, the fewer messages are printed,
    where ``error`` is highest and ``auth`` lowest.

    .. danger::
        The authentication exchange contains your password,
        even though this is not apparent.

.. confvar:: x509strict boolean

    Reject TLS certificates that do not conform to :RFC:`5280`?

    ``yes`` (default) or ``no``.


VARIABLES
=========

:samp:`~`, :samp:`~{user}`, :code:`$var`, and :code:`$\{var\}` are
expanded in commands and filenames.

:samp:`~` and :samp:`~{user}` are expanded to the home directory of the
current and the given `user` respectively, but only if they occur at
the start of a word.

:code:`$var` and :code:`$\{var\}` are expanded to the configuration
variable `var`. '\$' can be escaped by prefixing it with an additional
'\$' (e.g., :code:`$$var` is expanded to :code:`$var`).

Commands are split into words before '~' and variables are expanded.
Word-splitting is not performed on filenames.


FILES
=====

:file:`{$XDG_CONFIG_HOME}/sieve/sieverc`

:file:`{$HOME}/.sieve/sieverc`

:file:`{$HOME}/.sieverc`

:file:`/etc/sieve/sieverc`

:file:`/etc/sieverc`
    The configuration is read from the first file that exists.


EXAMPLES
========

Recommended configuration:

.. code:: none

    # Backup scripts before changing them
    backup simple

    # Only require confirmation for removing scripts
    confirm rm

    # Be less verbose
    verbosity warning

    # Accounts
    account imap.foo.example
        alias foo
        login user

    account imap.bar.example
        alias bar
        login user@bar.example

Lookup passwords stored by Apple Mail or MailMate_ in macOS' Keychain:

.. code:: none

    getpass security find-internet-password -s$host -a$login -w

Lookup passwords in `GNU Privacy Guard`_-encrypted files:

.. code:: none

    getpass gpg -d $confdir/$login@$host.gpg

Use TLS authentication to login as :samp:`user@bar.example`
on :file:`imap.bar.example`:

.. code:: none

    # Read passwords from encrypted files
    getpass gpg -d $confdir/$login@$host.gpg

    # Accounts
    account imap.foo.example
        alias foo
        login user

    account imap.bar.example
        alias bar
        authmechs external
        cert $confdir/client.crt
        key $confdir/client.key
        login user@bar.example


.. only:: man

    SEE ALSO
    ========

    :manpage:`sievemgr(1)`


.. _`GNU Privacy Guard`: https://gnupg.org

.. _MailMate: https://freron.com/

.. _SSL_CTX_load_verify_locations: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html#DESCRIPTION

.. _cryptography: https://cryptography.io

.. _emacs-backup: https://www.gnu.org/software/emacs/manual/html_node/emacs/Backup.html
